桌面模拟器（TTS）脚本API

在本节中，您将找到所有特定于《桌面模拟器》的Lua脚本的事件/类/函数的详细信息。关于Lua脚本语言如何工作以及它自己能做什么，您可以查看Lua官方文档。

这是在《桌面模拟器》中用Lua编写脚本时所需的类和其他信息的顶级列表。事件（Event）, 根基（Base）和对象（Object）是你使用最多的三个页面，其余的都是你可以访问的小众信息。熟悉这三页的内容有助于从高层次上理解脚本编写能够做什么。

目录将展示你所在页面的内容。它总是首先从高级摘要信息开始，如果需要，则从底部开始详细信息。！符号后的总结元素将直接将您带到下面的相关详细解释。

这个文档主要是用Markdown编写的，可以在Github上找到。

如果你遇到了一个错误，而这是你自己能够修复的，那么欢迎拉取请求。但是，如果您已经发现了一个问题，但不知道如何解决它，请通过打开一个问题让我们知道。

当前存在于场景中的游戏物理对象。如果一个对象被放置在包/牌组/等中，它将不再存在，直到它被拉出。

一个人在游戏。每个玩家被分配一个颜色，观众是“灰色”。如果你想要识别一个玩家，你可以使用他们所处位置的颜色。

每个游戏/保存都有一个全局脚本，它不附加到任何特定的对象。

只有一个全局脚本，并且它总是存在的。

每个游戏中的对象也可能有一个脚本附加到它。

默认情况下，新创建的对象没有附加脚本。但是，你可以从对象（Object）的上下文菜单中选择create/edit 该对象的脚本(通常通过右键单击对象打开)。

在《桌面模拟器》中，GUID是一个唯一的6个字符的字符串，可以用来识别游戏中的对象。当场景中存在对象时，该对象会自动分配到一个GUID。

如果一个对象被复制，在引擎给新的对象分配一个新的GUID之前，它有时会有1帧相同的GUID。容器中的对象(包/牌组/等)不会通过这种方式自动获得新的GUID。只有当他们的东西被移到现场时才会。

在本文档中，您可能会遇到Lua API，它们被标记为 deprecated 。建议您不要再使用已弃用的API。通常，这是因为引入了更新或改进的API，它们可以更好地服务于相同的目的。

弃用的API不会被移除或停止工作。

现有的Mod可以继续使用被弃用的功能。无论如何，强烈建议为了获得最佳体验，在新代码中避免使用已弃用的API。

类型（Types）是指所使用的信息的类型。您不需要在Lua中声明类型，但是在这个API中您将看到它们的指示。这只是为了让您知道在给定的变量/参数中需要什么样的信息。这个API利用以下类型。

更多信息见下文。

 有关类型的更多信息，可以阅读下面的内容或参考相关的Lua文档。

有些类型需要以特定的方式使用。对于Vector和Color，它们是在《桌游模拟器》中经常使用的表格Table。它们表示颜色和矢量，它们的内容必须以某种方式进行格式化才能正确使用。

对于函数，当运行中的脚本有特定的要求时需要延迟时，就会使用函数。

Color是Table的一种类型，用于定义着色的RGB值。

您可以使用Color类来操作颜色。

键

表中包含r,g,b,a和/或1,2,3,4 。字母键和数字键相互重复，每个键代表一种颜色或透明度。

例如，一个带有白色色调的Object会返回这个表:

注意，它不包含a或4键。这是因为目前只有脚本按钮和脚本输入使用alpha通道(透明度)。

混合键

只需要一种类型的键，数字或字母。如果两种都出现在Table中，则忽略数字键，只使用字母键。

值

每个键的值在0到1之间。如果您使用的是0-255的RGB颜色，您可以使用简单的数学转换为适当的值。

字符串

你也可以用一个字符串来代替颜色表。使用玩家颜色将自动填充该值。它适用于12种颜色名称中的任何一种，因为它们写在玩家颜色页面上。

例如：

Vector是一种带有x、y和z坐标的对象类型，用于定义位置、旋转或方向。

您可以使用Vector类来操作向量。

例如：

键

表将包含键x, y, z和/或1,2,3。字母键和数字键相同。

例如，在坐标X=5, Y=2, Z=-1处的一个对象将返回这个向量:

混合键

在引入Vector之前，坐标表包含1、2、3和x、y、z键下的单独值，字母键不同时优先。现在情况不再是这样了，使用字母和数字键是等价的。然而，当迭代Vector组件时，您必须使用pairs，并且只读取字母键。

值范围

值的范围取决于您使用的Vector类型。

类型细节

Position

X是右/左，Y是上/下，Z是前/后。位置向量可以是世界向量，也可以是局部向量。TTS中大多数的函数使用世界位置向量。

世界与局部坐标的转换

 positionToWorld(...) 和 positionToLocal(...) 被用来转换两种坐标

Rotation

X是俯仰(点头)，Y是偏航(摇头)，Z是滚转(头部倾斜)。

Direction

X是右/左，Y是上/下，Z是前/后。

函数（Function）是一段可以在触发时运行的代码。在Lua中，您可以传递(作为参数使用)函数。TTS中的一些元素可以通过传递函数来执行某些操作，比如在延迟后触发它。

用法

要传递一个函数，首先必须创建这个函数。有多种方法可以做到这一点:

你需要传递一个函数，而不是一个函数的结果。所以这是行不通的:

示例

 例如，这里的Wait.frames(…)被使用了3次。它等待一组帧，然后激活一个给定的函数:

游戏通常需要执行代码以响应游戏中发生的某些行动、互动或变化，统称为事件。

事件处理程序是您定义并由TTS调用的函数。

可以定义许多事件处理程序。每一个都为您提供了处理特定事件发生的机会。

当TTS调用你的函数，它将提供事件特定的细节作为你的事件处理函数的参数。

为了让TTS发现事件处理程序，必须将其定义为具有特定名称的全局变量。您使用的名称取决于您希望处理的事件。下面将介绍特定于事件的细节。

而事件处理程序名称只对应于一种类型的事件。每个事件可能有多个对应的事件处理程序(即事件处理程序名称)，TTS将查找和执行。

 事件处理程序有三种类型:

通用事件处理程序可以在全局脚本和/或对象脚本中定义。

全局事件处理程序只能在全局脚本中定义。

如果在对象脚本中使用全局事件处理程序的名称定义函数。它不会被调用。

对象事件处理程序只能在对象脚本中定义。

如果您在全局脚本中使用对象事件处理程序的名称定义函数。它不会被调用。

通常，如果一个事件有多个事件处理程序，例如在对象脚本、全局脚本和/或多个对象脚本中，那么所有这些事件处理程序都将被执行。

一些事件处理程序允许您返回一个值来触发可选的副作用。例如，从"try"事件处理程序返回false将阻止正在尝试的任何操作。如果返回触发可选副作用的值，则将不会执行后续事件处理程序(针对同一事件发生)。

如上所述，您可以在全局脚本或对象脚本中声明这些函数。

对象进入容器时调用。包括牌组

deprecated 请使用onObjectEnterZone(…)。

当对象进入脚本区域时调用。

deprecated 请使用onObjectLeaveZone(…)。

当对象离开脚本区时调用。

当按下脚本按钮（默认为整个小键盘的任意键）时调用。返回的索引范围为1 ~ 10。

如上所述，您可以在Global脚本中声明这些函数。

deprecated 请使用tryObjectEnterContainer(…)。

当对象试图进入容器时调用。

如上所述，你可以在对象脚本中声明这些函数。

这些事件属于脚本所有者-对象(在脚本中可用self访问)。

它们不能在全局脚本中声明这些事件处理程序。

deprecated 请使用tryObjectEnter(…)。

当对象试图输入脚本所有者object(容器)时调用。

这些是一个松散的函数集合，可用于在TTS中执行各种操作。

这些功能可以利用游戏内的对象，但它们都不能在游戏内的对象上执行。它们都与游戏空间有关。

在任何脚本中工作的通用函数。

deprecated 请使用getobject()。

返回包含游戏中除手牌区以外的所有物体的表格。

处理发送和显示数据的函数。

向外部脚本编辑器(最可能是Atom)发送一个表。这是为自定义编辑器功能。

对象类表示桌面模拟器中的任何实体。一旦你在你的脚本中有了一个对象的引用，你就可以直接在它上面调用函数。例如:obj.getPosition(…)。你可以通过多种方式获取一个对象的引用;

这些变量对所有对象都是通用的。有些变量是只读的，这意味着您可以查询属性，但不能为其赋新值。

通过将true赋值给locked来锁定/冻结对象。

 打印对象是否是locked。

当为false时，对象将不会被绘制在对象周围的常规(单击和拖动)选择框选中。

玩家可以在拖动选择的同时按住“Shift”修改器来覆盖这一行为。

确定用户悬停在对象上时可输入的最大数字数。

一旦玩家输入了最大数字数，相应的行为(如onObjectNumberTyped/onNumberTyped)就会立即触发，提高响应性。

当移动物体时，测量工具将自动被使用。

物体被拾取的旋转位置。只读。

如果这个对象是一个容器，它不能存在少于两个包含对象(例如，一个牌组)，取出最后一个包含对象将导致容器被销毁。在它的位置上，容器中最后一个剩余的对象将被生成。

这个变量在派生时提供对剩余对象的引用。否则，它是零。只读。

对象完成生成。只读。

已弃用。请使用 type。

物体翻转时是否切换旋转的轴。

与该对象相关联的数值，当鼠标悬停在该对象上时，将显示该数值。

在堆栈的情况下，UI中显示的值将乘以堆栈大小，也就是说，你可以使用值来创建自定义堆叠芯片。

当选择多个对象时，值将与共享重叠对象标记的对象一起求和。

已弃用。请使用 object tags

一些对象提供额外的行为。该功能可以作为Object成员变量访问，但将为nil，除非Object包含该行为。

“Counter”对象有一个Counter成员变量。我们将使用它来递增和检索计数器的值。

这些函数处理对象的物理属性:位置、旋转、缩放、边界、速度。换句话说，移动物体以及获取物体如何移动的信息。

这些函数处理与对象相关联的标记。单个标签是一组字符串，不区分大小写。

如果你想创建自己的系统，其中对象标签控制交互，规范的逻辑是，如果系统没有标签，它与所有东西交互，但如果它有任何标签，那么它只与共享其中一个的对象交互。例如(假设系统是由游戏内的对象所代表): 

一个新的UI系统被添加到桌面模拟器，它允许在对象上创建更灵活的UI元素。旧系统(经典UI)和新系统(自定义UI)都可以工作，而且各自有自己的优势。

经典UI

这些函数允许创建/编辑/删除功能按钮和文本输入，这些按钮和文本输入本身会触发脚本中的代码。这些按钮/输入附加到创建它们的对象上。

自定义UI

自定义UI为您提供了广泛的元素类型，而不仅仅是按钮和输入，以放置到对象上。它是UI类的扩展，关于其使用的详细信息可以在UI页面中找到。

这些函数从对象中获取信息。

颜色的色调。

返回对象的JSON字符串表示形式。适用于spawnObjectJSON(…)。

缩进是可选的，默认值为true。

返回附加到此对象的任何关节的信息。

返回一个关于对象状态的信息表。

这些函数将操作应用于对象。主要是修改对象的一些属性。

设置对象的值。根据对象的类型，表示一些不同的东西。

这些函数对对象执行一般操作。

作为参数提供的对象被销毁并成为一个虚拟的对象子对象。

重置该对象。重置一副牌会把所有的牌都带回来。重置一个包可以清除它的内容(对Loot和Infinite包都适用)。

为全局碰撞事件注销此对象。

组件api是一种高级特性。理解Unity的工作原理是使用它们的必要条件。有关更多信息，请参阅组件简介。

 这些函数可以隐藏对象，类似于手区域或隐藏区域的作用。

对指定的玩家隐藏对象，就像它在手牌区一样。

这些函数可以在对象中使用，也可以在游戏世界中使用全局函数。

AB包的行为出现在自定义AB包创建的对象上。

自定义PDF对象上显示书本行为。书本行为允许您操作显示的PDF。

例如，如果page_offset设置为10，那么UI中的第一个页面将是11，而不是1。负数是可以接受的，如果规则手册包含了PDF文件中的封面、索引等，那么负数是很有用的。

浏览器行为出现在平板电脑对象上。

指示一个平板对象加载桌面模拟器主页。

时钟行为出现在数字时钟对象上。

计数器行为出现在计数器对象上。

函数

增加计数器的值。

布局区域行为出现在布局区域上。

返回布局区域选项。

记录布局区域的选项。

布局区域选项表可能包含以下属性。

RPG小雕像行为出现在带有内置动画的对象上，例如RPG Kit对象。

这些是RPG小雕像成员变量，可以为其分配一个函数，该函数将在偶数发生时执行。

制作一个RPG雕像攻击。

文本工具的行为出现在3DText对象上，也就是那些用文本工具创建的对象。

组件api是一种高级特性。理解Unity的工作原理是使用它们的必要条件。

组件是一个函数和变量的集合，它允许你控制对象的行为。

组件是一个Unity概念，它们是构成桌面模拟器对象的构建块。

《桌面模拟器》中的每个对象都是游戏对象。当游戏被创建时，游戏对象被加载和初始化，一些顶级游戏对象将通过桌面模拟器的Lua脚本api作为常规对象暴露出来，每个对象都有自己的脚本上下文。

有些lua暴露的对象是由子游戏对象的层次结构组成的。组件api允许访问并与这些子游戏对象进行交互(否则你将无法控制)。

游戏对象本身是由组件组成的。典型的游戏对象应该包含Collider, Transform, Mesh等。这些组件描述了游戏对象的行为和视觉表现。

除了内置对象，组件api还提供了访问存在于AssetBundle中的游戏对象和组件。这意味着当你创建一个AssetBundle时，你可以附加所有的组件(灯光，声音等)，你可以通过这些api来控制它们。

每个组件都有多个变量。你可以修改这些变量来改变组件如何影响它所组成的游戏对象。

这些例子都是完整的脚本，可以放在一个常规的红块上。

禁用对象的阴影接收。

 禁用一个对象的(box)碰撞器。这通常会导致对象穿过表下落。

禁用一个对象的音频。物体将不再发出声音，例如，当从桌上拿起或掉在桌上时。当其他物体与该物体碰撞时，可能会继续发出声音。